<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
       "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html>

<head>
<title>Welcome Framework Enhancements</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
<meta http-equiv="Content-Style-Type" content="text/css" />
<link href="../Eclipse%20Doc%20Template/Eclipse%20Projects_files/dynamic_capabilities_files/default_style.css" type="text/css" rel="stylesheet" />
<script type="text/javascript" language="JavaScript">
<!--
function FP_changeProp() {//v1.0
 var args=arguments,d=document,i,j,id=args[0],o=FP_getObjectByID(id),s,ao,v,x;
 d.$cpe=new Array(); if(o) for(i=2; i<args.length; i+=2) { v=args[i+1]; s="o"; 
 ao=args[i].split("."); for(j=0; j<ao.length; j++) { s+="."+ao[j]; if(null==eval(s)) { 
  s=null; break; } } x=new Object; x.o=o; x.n=new Array(); x.v=new Array();
 x.n[x.n.length]=s; eval("x.v[x.v.length]="+s); d.$cpe[d.$cpe.length]=x;
 if(s) eval(s+"=v"); }
}

function FP_getObjectByID(id,o) {//v1.0
 var c,el,els,f,m,n; if(!o)o=document; if(o.getElementById) el=o.getElementById(id);
 else if(o.layers) c=o.layers; else if(o.all) el=o.all[id]; if(el) return el;
 if(o.id==id || o.name==id) return o; if(o.childNodes) c=o.childNodes; if(c)
 for(n=0; n<c.length; n++) { el=FP_getObjectByID(id,c[n]); if(el) return el; }
 f=o.forms; if(f) for(n=0; n<f.length; n++) { els=f[n].elements;
 for(m=0; m<els.length; m++){ el=FP_getObjectByID(id,els[n]); if(el) return el; } }
 return null;
}
// -->
</script>
</head>

<body bgcolor="#ffffff" style="position: relative; left: 0; top: 0">

<table width="100%">
	<tr>
		<td style="BACKGROUND: #0080c0"><span style="color: #FFFFFF"><b>Intro</b></span></td>
	</tr>
</table>
<h1>XHTML support in the Welcome Framework.</h1>
<blockquote>
	<b>Summary</b><br />
	This document describes the new <a href="http://www.w3.org/TR/xhtml1/">XHTML 
	1.0</a> support in the Eclipse 3.1 Welcome framework. This new feature is still 
	evolving, and feedback is welcomed.<p><font size="-1">Last modified: Feb 17, 
	2005</font></p>
	<p>&nbsp;</p>
</blockquote>
<p></p>
<h3>Background </h3>
<p>In Eclipse SDK 3.0, a new welcome framework was introduced to replace the existing 
editor-based welcome framework. It allowed for authoring Welcome pages using custom 
Intro XML markup. This kept content completely separate from presentation, which 
in turn was solely controlled by CSS or .properties files. A custom markup language 
was introduced to allow for the dynamic contribution to a given welcome page. This 
pluggable architecture for a given welcome page was needed to follow the same dynamic 
plugin nature of the platform itself. That is, a page can: </p>
<ul>
	<li>include content from other welcome pages.</li>
	<li>contribute content to another welcome pages. </li>
	<li>have content
	<a href="javascript:;" onclick="FP_changeProp(/*id*/'tooltip4',0,'style.display','inline')">
	<span style="cursor:help; text-decoration: none;">programmatically injected
	</span></a>into it.
	<span id="tooltip4" style="position: relative; display:none;" onclick="FP_changeProp(/*id*/'tooltip4',0,'style.display','none')">
	<font color="#0000FF" style="cursor: hand;">(This content is typically the result 
	of some query to the workbench through java code. An interface in the intro 
	framework allows for dynamically interacting with the generated HTML page and 
	populating the html page with more content, on the fly. For example, a welcome 
	page can dynamically create and display a list of projects in the workbench.)</font></span></li>
</ul>
<p>These features where implemented in 3.0 using a custom intro XML markup, and 
while the design satisfied the requirement, feedback pointed to the need for easier 
authoring. One such usability enhancement is to allow Welcome pages to be created 
by WYSIWYG editors, eliminating the need for the visual designer to know any details 
about the internals of the Intro framework. Once created, these pages can then be 
contributed as Welcome pages and assembled together into one coherent &quot;out of the 
box&quot; experience. </p>
<p>&nbsp;</p>
<h3>Proposed Solution</h3>
<p>Intro content will now be contributed with
<a href="javascript:;" onclick="FP_changeProp(/*id*/'tooltip1',0,'style.display','inline')">
<span style="cursor: help; text-decoration: none;">XHTML 1.0 documents</span></a>
<span id="tooltip1" style="position: relative; display:none;" onclick="FP_changeProp(/*id*/'tooltip1',0,'style.display','none')">
<font color="#0000FF" style="cursor: hand;">(A reformulation of the three HTML 4 
document types as applications of XML 1.0. For M5, only XHTML 1.0 is supported. 
XHTML 1.1 (module-based XHTML) can be supported, based on feedback.)</font></span>. 
The idea is to use the fact that XHTML is well formed XML and parse each document, 
manipulating the DOM to allow for contributions and extensions to be merged. 
Three xml elements from the 3.0 intro markup where used to extend the XHTML 1.0 
element list. These where <code>include</code>, <code>anchor</code>, and <code>
contentProvider</code>.
</p>
<ul>
	<li>&nbsp;<code><b>include</b>: </code>this element can be added to a valid 
	XHTML document to include content from another XHTML document. The content 
	to be included must be a valid XHTML snippet.</li>
</ul>
<blockquote>
	<dl>
		<dd>e.g.: <code>&lt;include path=&quot;root/foo&quot; /&gt;</code> will include an element 
	with id <code>foo</code> from a welcome page with id <code>root</code>.
</dd>
	</dl>
</blockquote>
<ul>
	<li>&nbsp;<code><b>anchor</b>: </code>this element can be added to a valid XHTML 
	document to declare that content can be contributed to this page by other 
	welcome contributions. A page declares locations that are suitable to be 
	extended by defining these anchor points.</li>
</ul>
<blockquote>
	<dl>
		<dd>e.g.: <code>&lt;anchor id=&quot;anchor1&quot; /&gt;</code> will allow for 
		contribution into this page from other plugins. </dd>
	</dl>
</blockquote>
<ul>
	<li><code><b>contentProvider</b>: </code>this element can be added to a valid XHTML 
	document to establish a hook into the workbench. When the intro framework 
	encounters this element, an interface is called allowing for the 
	manipulation of the DOM of the XHTML page. &nbsp;&nbsp; 
	</li>
</ul>
<dl>
	<dd>
	<dl>
		<dd>e.g.: <code>&lt;contentProvider id=&quot;contentProviderId&quot; 
		class=&quot;org.eclipse.ui.intro.template2.IntroXHTMLContentProvider&quot; 
		pluginId=&quot;org.eclipse.ui.intro.template2&quot;&gt; &lt;/contentProvider&gt; <br>
		</code>&nbsp;will allow for dynamic content to be generated from the <code>
		org.eclipse.ui.intro.template2.IntroXHTMLContentProvider</code> class.</dd>
	</dl>
	</dd>
</dl>
<p>With these three elements, XHTML pages can be used to assemble a pluggable 
and dynamic welcome experience.</p>
<p></p>
<p></p>
<blockquote>
	<address><b><span style="font-variant: small-caps">Note</span>: </b>if the only requirement is to render a tree of HTML documents 
		(from the file system or from the net), with no need for extensibility, 
		then this is already supported in Eclipse 3.0. A page can simply be defined 
		as follows:<br /><code>&nbsp;&nbsp;&nbsp; &lt;introContent&gt;<br />&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; &lt;page id=&quot;homePageId&quot; url=&quot;http://eclipse.org&quot;/&gt;<br />&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; &lt;page id=&quot;standbyPageId&quot; url=&quot;./static001/standby.html&quot;/&gt;<br />&nbsp;&nbsp;&nbsp; &lt;/introContent&gt;</code>
	</address>
	<address>The html page is loaded from the specified url, and displayed in the Welcome 
		view as is. In this scenario, the html page can make use of the custom intro 
		url actions. The browser in the welcome &quot;knows&quot; how to interpret these urls 
		in a special way, allowing for interaction with the workbench from a static 
		html page.
	</address>
	<address>
	</address>
</blockquote>
<h3>&nbsp;</h3>
<h3>Hello World Sample</h3>
<p>Here are the steps to create a Hello World XHTML Welcome page :&nbsp; </p>
<ul>
	<li><b>contribute a product </b>:</li>
</ul>
<dl>
	<dd>
	<pre><code>&lt;extension id=&quot;<i>product</i>&quot;</code><a href="javascript:;" onclick="FP_changeProp(/*id*/'tooltip5',0,'style.display','inline')"><span style="cursor: help; text-decoration: none;"><sup>1</sup></span></a> <span id="tooltip5" style="position: relative; display:none;" onclick="FP_changeProp(/*id*/'tooltip5',0,'style.display','none')"><font color="#0000FF" style="cursor: hand;">(<i>italic</i> means a user specified value) </font></span><code>point=&quot;org.eclipse.core.runtime.products&quot;&gt; 
    &lt;product name=&quot;<i>%example.product.name</i>&quot; 
        application=&quot;<i>org.eclipse.ui.ide.workbench</i>&quot;&gt; 
    &lt;/product&gt; 
&lt;/extension&gt;</code></pre>
	</dd>
</dl>
<ul>
	<li><b>contribute an intro part and bind it to the product you just created
	</b>:</li>
</ul>
<blockquote>
	<pre><code>&lt;extension point=&quot;org.eclipse.ui.intro&quot;&gt; 
    &lt;intro
        class=&quot;org.eclipse.ui.intro.config.CustomizableIntroPart&quot;
        id=&quot;<i>org.eclipse.ui.intro.template2.introId</i>&quot;&gt; 
    &lt;/intro&gt;
    &lt;introProductBinding
        introId=&quot;<i>org.eclipse.ui.intro.template2.introId</i>&quot;
        productId=&quot;<i>org.eclipse.ui.intro.template2.product</i>&quot;&gt;
    &lt;/introProductBinding&gt;
&lt;/extension&gt; </code></pre>
</blockquote>
<ul>
	<li><b>contribute a config (configuration) to the intro part you just 
	created :</b></li>
</ul>
<blockquote>
	<pre><code>&lt;extension point=&quot;org.eclipse.ui.intro.config&quot;&gt; 
    &lt;config id = &quot;<i>template2_configId</i>&quot; 
        introId=&quot;<i>org.eclipse.ui.intro.template2.introId</i>&quot; 
        content=&quot;<i>introContent.xml</i>&quot;&gt;
    &lt;presentation home-page-id=&quot;<i>root</i>&quot;&gt;
        &lt;implementation kind=&quot;html&quot;/&gt;
    &lt;/presentation&gt; 
    &lt;/config&gt; 
&lt;/extension&gt; </code></pre>
</blockquote>
<ul>
	<li><b>create an intro content file, introContent.xml, that describes all 
	your pages, and that you referenced in your intro configuration :</b></li>
</ul>
<blockquote>
	<pre><code>&lt;?xml version=&quot;1.0&quot; encoding=&quot;utf-8&quot; ?&gt;
&lt;introContent&gt;
    &lt;page id=&quot;root&quot; content=&quot;content/root.xhtml&quot;/&gt;
    &lt;page id=&quot;concept1&quot; content=&quot;content/concept1.xhtml&quot;/&gt;
    &lt;page id=&quot;concept2&quot; content=&quot;content/concept2.xhtml&quot;/&gt;
&lt;/introContent&gt;</code></pre>
</blockquote>
<ul>
	<li><b>create the actual XHTML pages referenced by the content file. Here is 
	root.xhtml :&nbsp; </b></li>
</ul>
<blockquote>
	<pre><code>&lt;!DOCTYPE html PUBLIC &quot;-//W3C//DTD XHTML 1.0 Transitional//EN&quot;
    &quot;http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd&quot;&gt;
&lt;html xmlns=&quot;http://www.w3.org/1999/xhtml&quot;&gt;
&lt;head&gt;
    &lt;meta http-equiv=&quot;Content-Type&quot; content=&quot;text/html; charset=utf-8&quot; /&gt;
    &lt;title&gt;root.xhtml&lt;/title&gt;
    &lt;link rel=&quot;stylesheet&quot; href=&quot;root.css&quot; type=&quot;text/css&quot; /&gt;
&lt;/head&gt;
&lt;body&gt;
    &lt;h1&gt;Welcome to Product A&lt;/h1&gt;
    &lt;h4 id=&quot;firstH4&quot;&gt;
        &lt;img border=&quot;0&quot; src=&quot;welcome_item.gif&quot; alt=&quot;Concept1&quot; /&gt;
        &lt;a href=&quot;http://org.eclipse.ui.intro/showPage?id=concept1&quot;&gt;Learn about Concept One... 
        &lt;/a&gt;
     &lt;/h4&gt;
    &lt;h4&gt;
        &lt;img border=&quot;0&quot; src=&quot;welcome_item.gif&quot; alt=&quot;Concept2&quot; /&gt;
        &lt;a href=&quot;http://org.eclipse.ui.intro/showPage?id=concept2&quot;&gt;Learn about Concept Two...&lt;/a&gt;
    &lt;/h4&gt;
    <b>&lt;anchor id=&quot;anchor1&quot; /&gt;</b>
&lt;/body&gt;
&lt;/html&gt;</code></pre>
</blockquote>
<ul>
	<li><b>launch a runtime-workbench with the product id you just created to 
	see the simple intro :</b></li>
</ul>
<blockquote>
	<p><code><img border="0" src="index.1.jpg"><br>
	<br>
&nbsp;</code></p>
	<p>&nbsp;</p>
</blockquote>
<h3>Extending the Hello World Sample</h3>
<p>Here are the steps to contribute to the above Hello World intro sample :&nbsp; </p>
<ul>
	<li><b>contribute a configExtension declaring that you want to extend the 
	original configuration </b>:</li>
</ul>
<dl>
	<dd>
	<pre><code>&lt;extension point=&quot;org.eclipse.ui.intro.configExtension&quot;&gt;
    &lt;configExtension configId=&quot;<i>template2_configId</i>&quot; 
        content=&quot;<i>ext.xml</i>&quot;/&gt;
&lt;/extension&gt; </code></pre>
	</dd>
</dl>
<ul>
	<li><b>create the extension content file and declare what the 
	extension content is. extensionContent element specifies the location of the 
	content file and the target path where this extension content needs to be 
	inserted. If this new content needs to reference other pages, these pages 
	can be declared in the same extension content file, as below :&nbsp; </b></li>
</ul>
<blockquote>
	<pre><code>&lt;?xml version=&quot;1.0&quot; encoding=&quot;utf-8&quot; ?&gt;
&lt;introContent&gt;
    &lt;extensionContent content=&quot;content/extContent.xhtml&quot; path=&quot;root/anchor1&quot; /&gt;
    &lt;page id=&quot;concept3&quot; content=&quot;content/concept3.xhtml&quot;/&gt;
&lt;/introContent&gt;</code></pre>
</blockquote>
<ul>
	<li><b>create the actual extension content, and save it as a separate file, 
	extContent.xml :</b></li>
</ul>
<blockquote>
	<pre><code>&lt;!DOCTYPE html PUBLIC &quot;-//W3C//DTD XHTML 1.0 Transitional//EN&quot;
	&quot;http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd&quot;&gt;
&lt;html xmlns=&quot;http://www.w3.org/1999/xhtml&quot;&gt;
&lt;head&gt;
	&lt;meta http-equiv=&quot;Content-Type&quot; content=&quot;text/html; charset=utf-8&quot; /&gt;
	&lt;title&gt;root.xhtml&lt;/title&gt;
	&lt;link rel=&quot;stylesheet&quot; href=&quot;root.css&quot; type=&quot;text/css&quot; /&gt;
&lt;/head&gt;
&lt;body&gt;
	&lt;h4&gt;
	  &lt;img border=&quot;0&quot; src=&quot;welcome_item.gif&quot; alt=&quot;Concept2&quot; /&gt;
	  &lt;a href=&quot;http://org.eclipse.ui.intro/showPage?id=concept3&quot;&gt;Learn about Concept Three...&lt;/a&gt;
  	&lt;/h4&gt;
&lt;/body&gt;
&lt;/html&gt;</code></pre>
</blockquote>
<ul>
	<li><b>launch a runtime-workbench with the product id of the product you created 
	to see the extension to the Hello World intro. We simply contributed a third 
	topic to the root page that launches the contributed page, <code>
	id=&quot;concept3&quot; </code>:</b></li>
</ul>
<blockquote>
	<p><img border="0" src="index.2.jpg"></p>
</blockquote>
<p>&nbsp;</p>
<ul>
	<li><b>the content of the third page uses the <code>include</code> and the
	<code>contentProvider</code> elements to include the first link from the 
	root page, and to print the current time. It is as follows : </b></li>
</ul>
<blockquote>
	<p>
	<iframe name="I1" src="concept3XHTML.htm" width="100%" height="280" style="border: 1px solid #FFFFFF">
	Your browser does not support inline frames or is currently configured not to display inline frames.
	</iframe></p>
</blockquote>
<p>&nbsp;</p>
<ul>
	<li><b>this is what the above page would look like after the intro elements 
	in it have been resolved. Notice the topic from the root page, and notice 
	the current time : </b></li>
</ul>
<blockquote>
	<p><img border="0" src="index.3.jpg"></p>
</blockquote>
<p>&nbsp;</p>
<h3>Document Conformance and file name extensions</h3>
<ul>
	<li>All documents used as intro pages must be valid XHTML 1.0 documents. XHTML 
	markup can be validated using w3.org <a href="http://validator.w3.org/">validators</a>.</li>
	<li>For conformance with existing HTML 4.0.1 browsers and to avoid running into 
	any compatibility issues, authors are encouraged to follow the
	<a href="http://www.w3.org/TR/xhtml1/#guidelines">compatibility guidelines</a> 
	document in the XHTML 1.0 specs. By doing so, an XHTML 1.0 page is nothing but 
	well-formed xml html.&nbsp; </li>
	<li>All XHTML documents must be UTF-8 encoded and the
	<a href="javascript:;" onclick="FP_changeProp(/*id*/'tooltip2',0,'style.display','inline')">
	<span style="cursor: help; text-decoration: none">XML declaration </span>
	</a>
	<span id="tooltip2" style="position: relative; display:none; cursor: hand;" onclick="FP_changeProp(/*id*/'tooltip2',0,'style.display','none')">
	<font color="#0000FF">(e.g.: &lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot; ?&gt;)</font>&nbsp;
	</span> must be avoided. This is a design/technical issue that is still evolving.
	<p></p>
	<h3>&nbsp;</h3>
	</li>
</ul>

</body>

</html>
